home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.2 for Intel / NeXTSTEP 3.2 for Intel.iso / NextLibrary / Documentation / Sybase / DBLIB / Section2 / dbmsghandle.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  4.3 KB  |  122 lines
  1. .Na "dbmsghandle" 
  2. .Aa
  3. .Fu
  4. Install a user function to handle \*S messages.
  5. .Ih "message handler, installing"
  6. .Ih "\*S messages"
  7. .Ih "messages, \*S"
  8. .Sy
  9. .Sf "int (*dbmsghandle(handler))()"
  10. .Sp "int" "(*handler)()"
  11. .Co
  12. .Bl
  13. \f2dbmsghandle()\f1 installs a message-handler function that you supply.
  14. When \*L receives a \*S error or informational message, it will
  15. call this message handler immediately.
  16. You must install a message handler
  17. in order to handle \*S messages properly.
  18. .Bl
  19. If the command buffer contains just a single command and that command provokes
  20. a \*S message, \*L will call the message handler during \f2dbsqlexec()\f1.
  21. If the command buffer contains multiple commands and one of the commands provokes
  22. a \*S message, \*L will call the message handler when
  23. \f2dbresults()\f1 is called for the particular command.
  24. .Bl
  25. You can de-install an existing message handler by calling \f2dbmsghandle()\f1 with a 
  26. NULL parameter.
  27. You can also, at any time, install a new message handler.
  28. The new handler will automatically replace any existing handler.
  29. .Bl
  30. See the \f2\*S Reference Supplement\f1 for a list of \*S messages.
  31. In addition, the \*N PRINT and RAISERROR commands generate \*S messages
  32. that \f2dbmsghandle()\f1 will catch.
  33. .Bl
  34. Another routine, \f2dberrhandle()\f1, installs an error handler that \*L calls
  35. in response to \*L errors.
  36. If the application provokes messages from \*L and \*S simultaneously,
  37. \*L calls the \*S message handler before it calls the \*L error handler.
  38. .mc |
  39. .Bl
  40. The routines \f2dbsetuserdata()\f1 and \f2dbgetuserdata()\f1 can be
  41. particularly useful when you need to transfer information between 
  42. the message handler and the program code that triggered it.
  43. See the \f2dbsetuserdata()\f1 manual page for an example of 
  44. how to handle deadlock in this way.
  45. .mc
  46. .Bz
  47. .Pa
  48. .Pi handler
  49. A pointer to the user function that will be called whenever
  50. \*L receives an error or informational message from \*S.
  51. \*L calls this function
  52. with eight parameters:
  53. .sp
  54. .in +10n
  55. .ta +10n
  56. .ti -10n
  57. \f2dbproc\f1    The affected DBPROCESS. 
  58. .sp 0.5v
  59. .ti -10n
  60. \f2msgno\f1    The current message's number (datatype \f2DBINT\f1).
  61. These numbers are documented in the \f2\*S Reference Supplement\f1.
  62. .sp 0.5v
  63. .ti -10n
  64. \f2msgstate\f1    The current message's error state number (datatype \f2int\f1).
  65. These numbers provide Sybase Customer Support with information about the context of the error.
  66. .sp 0.5v
  67. .ti -10n
  68. \f2severity\f1    The current message's information class or error severity (datatype \f2int\f1).
  69. These numbers are documented in the \f2System Administration Guide\f1.
  70. .sp 0.5v
  71. .ti -10n
  72. \f2msgtext\f1    The null-terminated text of the current message (datatype \f2char *\f1).
  73. .sp 0.5v
  74. .mc |
  75. .ti -10n
  76. \f2srvname\f1    The null-terminated name of the server that generated the message
  77. (datatype \f2char *\f1).
  78. A server's name is
  79. stored in the \f2srvname\f1 column of its \f2sysservers\f1 system table.
  80. It is used in server-to-server communication; in particular, it's used
  81. when one server logs into another server to perform a remote procedure call.
  82. If the server has no name, \f2srvname\f1 will be of length 0.
  83. .sp 0.5v
  84. .ti -10n
  85. \f2procname\f1    The null-terminated name of the stored procedure
  86. that generated the message (datatype \f2char *\f1).
  87. If the message was not generated by a stored procedure, \f2procname\f1 will be of length 0.
  88. .sp 0.5v
  89. .ti -10n
  90. \f2line\f1    The number of the command batch or stored procedure line that
  91. generated the message (datatype \f2DBUSMALLINT\f1).
  92. Line numbers start at 1.
  93. The line number pertains to the nesting level at which the message was generated.
  94. For instance, if a command batch executes stored procedure A, which then calls
  95. stored procedure B, and a message is generated at line 3 of B, then \f2line\f1 will be 3.
  96. .sp 0.5v
  97. \f2line\f1 will be 0 if there is no line number associated with the message.
  98. Circumstances that could generate messages without line numbers include
  99. a login error or a remote procedure call (performed via \f2dbrpcsend()\f1)
  100. to a stored procedure that doesn't exist.
  101. .sp
  102. .in -10n
  103. The message handler must return a value of 0 to \*L.
  104. .sp
  105. .mc
  106. The following example shows a typical message handler routine:
  107. .ta +4n +4n +4n +4n +4n +4n
  108. .SD
  109. .mc |
  110. .so dbmsghandle.ex
  111. .mc
  112. .ED
  113. .in -.375i
  114. .Re
  115. .br
  116. A pointer to the previously-installed message handler.
  117. This may be NULL.
  118. .Sa
  119. dberrhandle,
  120. dbgetuserdata,
  121. dbsetuserdata
  122.